add documentation for some options. (#334)

* add documentation for some options.

garmin_gpi: languagecode
gpx: elevprec

* doc wording tweak.

* delete obsolete unused lowranceusr option,

and document new lowranceusr options.

* tweak doc.

diff --git a/lowranceusr.cc b/lowranceusr.cc
index e51acca31205cb91205ab9d3e3a7b99167a8426e..a1c26da691fa3a2d275c488fc6ae6d4aab168ede 100644 (file)
--- a/lowranceusr.cc
+++ b/lowranceusr.cc
@@ -329,7 +329,6 @@ static char*          opt_ignoreicons;
 static char*          opt_writeasicons;
 static char*          opt_seg_break;
 static char*          opt_wversion;
-static char*          opt_rversion;
 static char*          opt_title;
 static char*          opt_content_descr;
 static char*          opt_serialnum;
@@ -722,12 +721,6 @@ arglist_t lowranceusr_args[] = {
     "break", &opt_seg_break, "(USR input) Break segments into separate trails",
     nullptr, ARGTYPE_BOOL, ARG_NOMINMAX, nullptr
   },
-  {
-    // Specify the Input USR Version to be interpreted
-    // Obsolete option that is ignored
-    "rversion", &opt_rversion, "(USR input) Read version",
-    "", ARGTYPE_STRING, ARG_NOMINMAX, nullptr
-  },
   {
     // Specify the Output USR Version to be generated
     "wversion", &opt_wversion, "(USR output) Write version",

diff --git a/xmldoc/formats/options/garmin_gpi-languagecode.xml b/xmldoc/formats/options/garmin_gpi-languagecode.xml
new file mode 100644 (file)
index 0000000..87c966e
--- /dev/null
+++ b/xmldoc/formats/options/garmin_gpi-languagecode.xml
@@ -0,0 +1,34 @@
+<para>
+Garmin points of interest files may contain data in two languages.
+If you attempt to read a dual language Garmin points of interest file without specifiying which language
+to use GPSBabel will print an error message containing the language codes used in the file.
+Subsequently you may use one of these codes with the languagecode
+option to specify which language to use.
+</para>
+<example id="gpi_languagecode_notspecified">
+  <title>Example with unspecified language and a garmin points of interest dual language file.</title>
+  <para>
+    <userinput>
+      gpsbabel -i garmin_gpi -f reference/spb_metro_norm.gpi
+    </userinput>
+    could produce the following output:
+    <simplelist type="vert">
+      <member>garmin_gpi: Must select language code, RU and EN found.</member>
+    </simplelist>
+  </para>
+</example>
+<example id="gpi_languagecode_specified">
+  <title>Example for specifying language with a garmin points of interest dual language file.</title>
+  <para>
+    <userinput>
+      gpsbabel -i garmin_gpi,languagecode=EN -f reference/spb_metro_norm.gpi 
+    </userinput>
+    could produce the following output:
+    <simplelist type="vert">
+      <member>59.944070N 30.306680E About Saint-Petersburg Metro - 2016.05/This file represents information about metro stations in aint-Petersburg. Published by NAVICOM, 2016. http://navicom.ru</member>
+      <member>59.830660N 30.500100E RYBACKOE/Subway</member>
+      <member>59.934430N 30.329950E NEVSKII PROSPEKT/Subway</member>
+      <member>...</member>
+    </simplelist>
+  </para>
+</example>

diff --git a/xmldoc/formats/options/gpx-elevprec.xml b/xmldoc/formats/options/gpx-elevprec.xml
new file mode 100644 (file)
index 0000000..8e08da0
--- /dev/null
+++ b/xmldoc/formats/options/gpx-elevprec.xml
@@ -0,0 +1,18 @@
+<para>
+This option specifies the number of digits to be used when
+writing elevation values.
+Precision is the number of digits after the decimal point.  The default
+precision is 3.  We limit the number of places we write to improve the
+fidelity when round-tripping elevation, reduce file size, and reduce 
+silliness in files caused by repeating decimals in insignificant 
+digits.
+</para>
+<para>
+As a guideline, three decimal places is 1 millimeter.
+To achieve precision approaching this limit leveling techniques are required.
+Precisions beyond this are not currently obtainable.
+</para>
+<para>
+This value is ignored on read and has no impact on the internal 
+representation of data.
+</para>

diff --git a/xmldoc/formats/options/lowranceusr-description.xml b/xmldoc/formats/options/lowranceusr-description.xml
new file mode 100644 (file)
index 0000000..dea5927
--- /dev/null
+++ b/xmldoc/formats/options/lowranceusr-description.xml
@@ -0,0 +1,3 @@
+<para>
+This option can be used when writing a version 4 or higher Lowrance USR file to set the description text.  If the option is not used the description text will be "Waypoints, routes, and trails".
+</para>

diff --git a/xmldoc/formats/options/lowranceusr-serialnum.xml b/xmldoc/formats/options/lowranceusr-serialnum.xml
new file mode 100644 (file)
index 0000000..2bd84a9
--- /dev/null
+++ b/xmldoc/formats/options/lowranceusr-serialnum.xml
@@ -0,0 +1,7 @@
+<para>
+This option can be used when writing a version 4 or higher Lowrance
+USR file to set the device serial number.
+If the option is not used and the source of the data is a Lowrance USR
+file with a valid serial number then that serial number will be used,
+otherwise a value of 0 will be used.
+</para>

diff --git a/xmldoc/formats/options/lowranceusr-title.xml b/xmldoc/formats/options/lowranceusr-title.xml
new file mode 100644 (file)
index 0000000..8d4a09d
--- /dev/null
+++ b/xmldoc/formats/options/lowranceusr-title.xml
@@ -0,0 +1,3 @@
+<para>
+This option can be used when writing a version 4 or higher Lowrance USR file to set the file title.  If the option is not used the title will be "GPSBabel generated USR data file".
+</para>